home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 August: Tool Chest / Dev.CD Aug 94.toast / Sample Code / AppsToGo / DTS.Lib / DTS.Lib.headers / TreeObj.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-03-24  |  18.2 KB  |  532 lines  |  [TEXT/MPS ]
  1. #ifndef __TREEOBJ__
  2. #define __TREEOBJ__
  3.  
  4. #ifndef __TYPES__
  5. #include <Types.h>
  6. #endif
  7.  
  8. #ifndef __ERRORS__
  9. #include <Errors.h>
  10. #endif
  11.  
  12. #ifndef __EVENTS__
  13. #include <Events.h>
  14. #endif
  15.  
  16. #ifndef __MEMORY__
  17. #include <Memory.h>
  18. #endif
  19.  
  20. #define NO_EDIT 0                        /* System edit type. */
  21.  
  22.  
  23. /********/
  24.  
  25.  
  26. #define EMPTYOBJ    0
  27. #define ROOTOBJ     1
  28. #define UNDOOBJ     2
  29. #define UNDOTASKOBJ 3
  30. #define UNDOPARTOBJ 4
  31. #define WFMTOBJ     5
  32. #define CTLOBJ      6
  33.  
  34. #define kCStr       0
  35. #define kPStr       1
  36. #define kSDataBlock 2
  37. #define kLDataBlock 3
  38.  
  39. #if defined(powerc) || defined (__powerc)
  40. #pragma options align=mac68k
  41. #endif
  42. struct FileRec;
  43. typedef struct FileRec *FileRecPtr, **FileRecHndl;
  44. #if defined(powerc) || defined(__powerc)
  45. #pragma options align=reset
  46. #endif
  47.  
  48. #if defined(powerc) || defined (__powerc)
  49. #pragma options align=mac68k
  50. #endif
  51. struct TreeObj;
  52. typedef struct TreeObj *TreeObjPtr, **TreeObjHndl;
  53. typedef long    (*TreeObjProcPtr)(TreeObjHndl hndl, short message, long data);
  54. #if defined(powerc) || defined(__powerc)
  55. #pragma options align=reset
  56. #endif
  57.  
  58. #if defined(powerc) || defined (__powerc)
  59. #pragma options align=mac68k
  60. #endif
  61. typedef struct TreeObj {
  62.     short        type;
  63.     short        numChildren;
  64.     long        dataSize;
  65.     long        treeID;
  66.     TreeObjHndl    parent;
  67. } TreeObj;
  68. #if defined(powerc) || defined(__powerc)
  69. #pragma options align=reset
  70. #endif
  71.  
  72. #if defined(powerc) || defined (__powerc)
  73. #pragma options align=mac68k
  74. #endif
  75. long    TUndoObj(TreeObjHndl hndl, short message, long data);
  76. typedef struct {
  77.     TreeObjHndl    root;
  78.     FileRecHndl    frHndl;
  79.     Boolean        disabled;
  80.     short        lastEditType;
  81.     short        undoDepth;
  82.     short        maxNumUndos;
  83.     short        numSaveUndos;
  84. } UndoObj;
  85. #if defined(powerc) || defined(__powerc)
  86. #pragma options align=reset
  87. #endif
  88.  
  89. #if defined(powerc) || defined (__powerc)
  90. #pragma options align=mac68k
  91. #endif
  92. long    TUndoTaskObj(TreeObjHndl hndl, short message, long data);
  93. typedef struct {
  94.     short    editType;
  95.     Point    undoOrigin;
  96.     Point    redoOrigin;
  97. } UndoTaskObj;
  98. #if defined(powerc) || defined(__powerc)
  99. #pragma options align=reset
  100. #endif
  101.  
  102. #if defined(powerc) || defined (__powerc)
  103. #pragma options align=mac68k
  104. #endif
  105. long    TUndoPartObj(TreeObjHndl hndl, short message, long data);
  106. typedef struct {
  107.     short        actionType;
  108.     TreeObjHndl    shndl;
  109.     short        scnum;
  110.     TreeObjHndl    dhndl;
  111.     short        dcnum;
  112.     Boolean        deepCopy;
  113. } UndoPartObj;
  114. #if defined(powerc) || defined(__powerc)
  115. #pragma options align=reset
  116. #endif
  117.  
  118. #if defined(powerc) || defined (__powerc)
  119. #pragma options align=mac68k
  120. #endif
  121. struct VHFormatData {
  122.     Handle    text;
  123.     char    *header;
  124.     char    *data;
  125. };
  126. typedef struct VHFormatData VHFormatData;
  127. typedef VHFormatData *VHFormatDataPtr;
  128. #if defined(powerc) || defined(__powerc)
  129. #pragma options align=reset
  130. #endif
  131.  
  132. #define mDerefUndo(hndl)     ((UndoObj*)((*hndl) + 1))
  133. #define mDerefUndoTask(hndl) ((UndoTaskObj*)((*hndl) + 1))
  134. #define mDerefUndoPart(hndl) ((UndoPartObj*)((*hndl) + 1))
  135.  
  136.  
  137. /********/
  138.  
  139.  
  140. #define INITMESSAGE        0        /* Additional object initialization. */
  141. #define     CREATEINIT         0    /* Object being initially created. */
  142. #define     WINDOWINIT         1    /* Document/object being assigned to a window. */
  143. #define     NOWINDOWINIT       2    /* Document/object being freed from a window. */
  144.  
  145. #define FREEMESSAGE        1        /* Additional object disposal. */
  146.  
  147. #define COPYMESSAGE        2        /* Additional object cloning. */
  148.  
  149. #define UNDOMESSAGE        3        /* Additional object undo. */
  150. #define     UNDOFROMDOC        0    /* Object leaving document. */
  151. #define     UNDOTODOC          1    /* Object returning to document. */
  152.  
  153. #define CONVERTMESSAGE     4        /* Hndl2ID or ID2Hndl conversions. */
  154. #define     CONVERTTOID        0    /* Convert handle references to ID references. */
  155. #define     CONVERTTOHNDL    1        /* Convert ID references to handle references. */
  156.  
  157. #define FREADMESSAGE       5        /* Read object data from file. */
  158. #define FWRITEMESSAGE      6        /* Write object data to file. */
  159.  
  160. #define HREADMESSAGE       7        /* Read object data from handle. */
  161. #define HWRITEMESSAGE      8        /* Write object data to handle. */
  162.  
  163. #define HITTESTMESSAGE     9        /* Test if object was hit. */
  164. #define     HITTESTOBJ         0    /* Test body of object for hit. */
  165. #define     HITTESTGRABBER     1    /* Test sizing parts for hit. */
  166. #define     CANBETARGET        2    /* Return true if object can become target. */
  167. #define     CANTAKEKEYS        3    /* Return true if target can take keys. */
  168.  
  169. #define GETRGNMESSAGE      10        /* Return object defining rect. */
  170. #define GETOBJRECTMESSAGE  11        /* Return object defining rect. */
  171. #define SETOBJRECTMESSAGE  12        /* Set object bounding box. */
  172. #define SECTOBJRECTMESSAGE 13        /* Check if rect intersects object bounding box. */
  173.  
  174. #define GETBBOXMESSAGE     14        /* Return rect that contains entire graphic image. */
  175.  
  176. #define DRAWMESSAGE        15        /* Draw some form of the object. */
  177. #define     DRAWOBJ            0    /* Draw the object. */
  178. #define     ERASEOBJ           1    /* Draw the object. */
  179. #define     DRAWSELECT         2    /* Draw the selection portion of the object. */
  180. #define     DRAWGHOST          3    /* Draw an xor-ghost (for dragging) of the image. */
  181. #define     DRAWMASK           4    /* Draw a mask of the image (for offscreen layer masking.) */
  182.  
  183. #define PRINTMESSAGE       16
  184.  
  185. #define VHMESSAGE          17        /* Format View Hierarchy information for the object. */
  186.  
  187. #define COMPAREMESSAGE     18        /* Compare data of two objects of same type. */
  188.  
  189.  
  190.  
  191. #define DOUNDO 0
  192. #define DOREDO 1
  193.  
  194.  
  195.  
  196. TreeObjHndl    NewRootObj(short ctype, long size);
  197.     /* Creates an object with no parent.  This object will be the root object
  198.     ** for a tree.  Returns nil upon failure. */
  199.  
  200.  
  201.  
  202. TreeObjHndl    NewChild(short editType, TreeObjHndl parentHndl, short childNum, short ctype, long size);
  203.     /* Creates a child of the specified type and adds it to the parent at the
  204.     ** specified location.  Returns nil upon failure. */
  205.  
  206.  
  207.  
  208. void        DisposeChild(short editType, TreeObjHndl parentHndl, short childNum);
  209.     /* Disposes of the specified child and all offspring of that child. */
  210.  
  211.  
  212.  
  213. TreeObjHndl    CopyChild(short editType, TreeObjHndl shndl, short scnum, TreeObjHndl dhndl, short dcnum, Boolean deepCopy);
  214.     /* Copies the specified child (and all offspring of that child if deepCopy is true). */
  215.  
  216.  
  217.  
  218. OSErr        MoveChild(short editType, TreeObjHndl shndl, short scnum, TreeObjHndl dhndl, short dcnum);
  219.     /* Moves a child from one location on the tree to another. */
  220.  
  221.  
  222.  
  223. OSErr        ModifyChild(short editType, TreeObjHndl phndl, short cnum, Boolean deepCopy);
  224.     /* Saves a copy of the child in the undo hierarchy for undo/redo purposes. */
  225.  
  226.  
  227.  
  228. OSErr        SwapChildren(short editType, TreeObjHndl hndla, short cnuma, TreeObjHndl hndlb, short cnumb);
  229.     /* Swaps the child handles. */
  230.  
  231.  
  232.  
  233. OSErr        SwapTreeObjData(TreeObjHndl hndla, TreeObjHndl hndlb);
  234.     /* Swaps the child data without swapping the handles. */
  235.  
  236.  
  237.  
  238. void        DisposeObjAndOffspring(TreeObjHndl childHndl);
  239.     /* This disposes of the child and any offspring of that child.  It does not remove
  240.     ** the child from the parent's child handle table. */
  241.  
  242.  
  243.  
  244. OSErr        CopyChildren(TreeObjHndl shndl, TreeObjHndl dhndl);
  245.     /* Copies the children (and children below that and so on) of one object to
  246.     ** another object.  Used internally by CopyChild for deep copies. */
  247.  
  248.  
  249.  
  250. OSErr        InsertChildHndl(TreeObjHndl parentHndl, TreeObjHndl childHndl, short childNum);
  251.     /* Adds an existing child to a parent's child handle table. */
  252.  
  253.  
  254.  
  255. void        DeleteChildHndl(TreeObjHndl parentHndl, short childNum);
  256.     /* Removes a child from the parent's child handle table. */
  257.  
  258.  
  259.  
  260. TreeObjHndl    GetRootHndl(TreeObjHndl hndl);
  261.     /* Given an object handle, return the root handle. */
  262.  
  263.  
  264.  
  265. TreeObjHndl    GetChildHndl(TreeObjHndl parentHndl, short cnum);
  266.     /* Given a parent handle and a child number, this returns the child handle. */
  267.  
  268.  
  269.  
  270. TreeObjHndl    *GetChildHndlPtr(TreeObjHndl parentHndl, short *childNum, short endCase);
  271.     /* Return a pointer into the child handle table.  This also validates (and corrects)
  272.     ** cnum so that it is in range, if possible.  Depending on the usage, pointing to
  273.     ** just after the child handle table is either valid or invalid.  If a handle is
  274.     ** being added to the table, then pointing just after the table is valid.  If a
  275.     ** handle is being removed or referenced, then pointing just after the table is
  276.     ** invalid.  the parameter endCase determines which case we are dealing with.  If
  277.     ** endCase is 0, then pointing just after the child handle table is invalid, and
  278.     ** if the cnum value passed in causes this, then nil is returned for the pointer.
  279.     ** if endCase is 1, then pointing just after the child handle table is okay, and
  280.     ** therefore nil will never be returned as the pointer.  Any cnum value out of
  281.     ** range will be corrected (if possible) to be within range. */
  282.  
  283.  
  284.  
  285. short        GetChildNum(TreeObjHndl hndl);
  286.     /* Given a child handle, this returns the child number of that
  287.     ** handle in the parent's child handle table. */
  288.  
  289.  
  290.  
  291. OSErr        AdjustDataSize(TreeObjHndl hndl, long delta);
  292.     /* Adjusts the data size, either greater or smaller, depending on the sign of 'delta'. */
  293.  
  294.  
  295.  
  296. OSErr        SetDataSize(TreeObjHndl hndl, long newSize);
  297.     /* Sets the data size to newSize. */
  298.  
  299.  
  300.  
  301. OSErr        SlideData(TreeObjHndl hndl, long offset, long delta);
  302.     /* Slides some of the data in the data portion of the object starting at
  303.     ** 'offset' by a 'delta' amount, either forward or backward, depending
  304.     ** on the sign of 'delta'. */
  305.  
  306.  
  307.  
  308. void        *GetDataPtr(TreeObjHndl hndl);
  309.     /* Returns a pointer to the beginning of the object's data area.
  310.     ** THIS DOES NOT LOCK THE HANDLE!!  The pointer may become invalid
  311.     ** if memory moves. */
  312.  
  313.  
  314.  
  315. OSErr        ReadTree(TreeObjHndl hndl, short fileRefNum);
  316.     /* Given an open file that has been previously written via WriteTree, this function
  317.     ** is called to read the file data into ram.  The root object for the file is already
  318.     ** created by InitDocument.  The file must be open, and the file position must be
  319.     ** set to the byte location where the root object of the file starts.  Once this is
  320.     ** so, just call this function with a reference to the root object and the open file
  321.     ** refrence number. */
  322.  
  323.  
  324.  
  325. OSErr        ReadTreeObjData(TreeObjHndl hndl, short fileRefNum);
  326.     /* Read in dataSize number of bytes into the object. */
  327.  
  328.  
  329.  
  330. OSErr        WriteTree(TreeObjHndl hndl, short fileRefNum);
  331.     /* Given an open file that is ready to be written to, this function is called to
  332.     ** write the file tree to the designated file. */
  333.  
  334.  
  335.  
  336. OSErr        WriteTreeObjData(TreeObjHndl hndl, short fileRefNum);
  337.     /* Write out dataSize number of bytes from the object. */
  338.  
  339.  
  340.  
  341. void        DoBTreeMethod(TreeObjHndl hndl, short message, long data);
  342.     /* Call the object for each member of the tree (or branch) starting
  343.     ** from the back of the tree working forward. */
  344.  
  345.  
  346.  
  347. OSErr        DoErrBTreeMethod(TreeObjHndl hndl, short message, long data);
  348.     /* Same as DoBTreeMethod, except that an error aborts tree walk and returns error. */
  349.  
  350.  
  351.  
  352. void        DoFTreeMethod(TreeObjHndl hndl, short message, long data);
  353.     /* Call the object for each member of the tree (or branch) starting
  354.     ** from the front of the tree working backward. */
  355.  
  356.  
  357.  
  358. OSErr        DoErrFTreeMethod(TreeObjHndl hndl, short message, long data);
  359.     /* Same as DoFTreeMethod, except that an error aborts tree walk and returns error. */
  360.  
  361.  
  362.  
  363. long        DoTreeObjMethod(TreeObjHndl hndl, short message, long data);
  364.     /* If the object has a method procedure, call it.  If no method procedure,
  365.     ** then do nothing. */
  366.  
  367.  
  368.  
  369. void        DoNumberTree(TreeObjHndl hndl);
  370.     /* Number each member in the tree with a unique treeID.  The tree is number
  371.     ** sequentially from front to back.  The first treeID number is 1.  0 is
  372.     ** reserved for Hndl2ID/ID2Hndl conversions where it is possible that the
  373.     ** handle value is nil.  The nil handle will convert to 0, and convert back
  374.     ** to nil. */
  375.  
  376.  
  377.  
  378. void        Hndl2ID(TreeObjHndl *hndl);
  379.     /* This function is used to convert a handle reference into a treeID reference.
  380.     ** A pointer to the handle reference is passed in.  Typical usage will be where
  381.     ** a handle object has a reference to another handle object.  Handle object
  382.     ** references aren't meaningful when saved to disk, and therefore don't persist
  383.     ** in their native form.  These handle references need to be converted into
  384.     ** a treeID reference so that they can be saved.
  385.     ** The tree first needs to be numbered so that the treeID references are unique
  386.     ** and meaningful.  The tree is numbered by first calling DoNumberTree().  It
  387.     ** numbers all the members of the tree hierarchy uniquely and sequentially. */
  388.  
  389.  
  390.  
  391. void        ID2Hndl(TreeObjHndl refHndl, TreeObjHndl *hndl);
  392.     /* Given a tree object ID and a reference object (any member of the tree),
  393.     ** return the cooresponding object handle.  DoNumberTree() must be called
  394.     ** prior to using this function, and after the last change to the tree, as
  395.     ** it generates the object treeID numbers for the entire tree. */
  396.  
  397.  
  398.  
  399. TreeObjHndl    GetUndoHndl(TreeObjHndl hndl);
  400.     /* Given an object handle, return the undo handle. */
  401.  
  402.  
  403.  
  404. void        NewUndo(TreeObjHndl hndl);
  405.     /* Used to close out an old undo task.  Closing out the old task means that
  406.     ** any editing to the document will be recorded into a new undo task.  Use
  407.     ** this to separate two edits of the same edit type that would otherwise
  408.     ** get recorded into the same undo task. */
  409.  
  410.  
  411.  
  412. void        RevertEdit(TreeObjHndl hndl, Boolean fixup);
  413.     /* If an edit fails, it can be backed out of by calling this.  All edits
  414.     ** that were done will be undone, thus recovering the state of the
  415.     ** document prior to the edit. */
  416.  
  417.  
  418.  
  419. void        DoUndoTask(TreeObjHndl hndl, Boolean redo, Boolean fixup);
  420.     /* Call this to undo or redo editing to the document.  If redo is false,
  421.     ** the it is an undo task.  If fixup is true, then the fixup application's
  422.     ** undo fixup procedure is called before and after the undo operation. */
  423.  
  424.  
  425.  
  426. void        DisableUndo(TreeObjHndl hndl);
  427.     /* Dispose of all undo information and prevent further undo collection.
  428.     ** Calling NewUndo() will re-enable undo collection. */
  429.  
  430.  
  431.  
  432. void        DisposeUndos(TreeObjHndl hndl);
  433.     /* Dispose of all undo information. */
  434.  
  435.  
  436.  
  437. Boolean        PurgeUndo(TreeObjHndl hndl);
  438.     /* Dispose of all undo information except the current undo.  The current undo
  439.     ** may still be active, and it may be needed to back out of an edit operation. */
  440.  
  441.  
  442.  
  443. void        GetUndoInfo(FileRecHndl frHndl, short *undoDepth, short *numUndos);
  444.     /* Return the depth of the undo state, along with the number of undos.  This
  445.     ** is useful to determine if undo and redo operations are possible.  If undoDepth
  446.     ** is non-zero, then undo is possible.  If numUndos is greater than undoDepth,
  447.     ** then redo is possible. */
  448.  
  449.  
  450.  
  451. OSErr    DefaultInitDocument(FileRecHndl frHndl, short version, short numUndos, short numSaveUndos);
  452. OSErr    DefaultFreeDocument(FileRecHndl frHndl);
  453. OSErr    DefaultReadDocument(FileRecHndl frHndl);
  454. OSErr    DefaultReadDocumentFixup(FileRecHndl frHndl);
  455. OSErr    DefaultWriteDocument(FileRecHndl frHndl);
  456.     /* These functions are called when the standard behaviors are what is desired.
  457.     **
  458.     ** DefaultInitDocument:
  459.     **        Create a root object and an undo root object.  The undo root has the numUndos
  460.     **        and numSaveUndos values placed in it.
  461.     **
  462.     ** DefaultFreeDocument:
  463.     **        Dispose of the document and undo information.  It assumes a normal hierarchical
  464.     **        document architecture and undo root for the document. 
  465.     **
  466.     ** DefaultReadDocument:
  467.     **        Read a standard hierarchical document from a file.  It assumes that the document
  468.     **        was written with DefaultWriteDocument.  There may be handle-to-id conversions
  469.     **        still to do.  The entire document must first be read in before this can occur.
  470.     **        A separate pass through the doucment is made, giving each object a chance to
  471.     **        convert id's back into handle references.
  472.     **
  473.     ** DefaultReadDocumentFixup:
  474.     **        Fixup the document that was just read in.  When a document is written out using
  475.     **        DefaultWriteDocument, some number of undo tasks may have been moved onto the
  476.     **        end of the document.  This function moves the undo tasks out of the document
  477.     **        and into the undo root.
  478.     **
  479.     ** DefaultWriteDocument:
  480.     **        Write a standard hierarchical document to disk.  The number of undos to save
  481.     **        (indicated by the numSaveUndos field in the undo root) are first moved to the
  482.     **        end of the document.  The document is then saved starting with the document
  483.     **        root.
  484.     */
  485.  
  486.  
  487.  
  488. OSErr    HReadTree(TreeObjHndl hndl, Handle tree);
  489. OSErr    HReadBranch(TreeObjHndl hndl, Handle tree);
  490. OSErr    HReadTreeObjData(TreeObjHndl hndl, Handle treeObjData);
  491. OSErr    HWriteTree(TreeObjHndl hndl, Handle tree);
  492. OSErr    HWriteTreeObjData(TreeObjHndl hndl, Handle data);
  493.     /* These functions work the same as the non-handle based versions.  Instead of
  494.     ** reading or writing to a file, these read or write to a handle.  This allows
  495.     ** you to stream the hierarchical data into a single handle that can be stored
  496.     ** as a resource or sent to another application via AppleEvents. */
  497.  
  498.  
  499.  
  500. long            GetCData(TreeObjHndl hndl, long offset, char *data);
  501. OSErr            PutCData(TreeObjHndl hndl, long offset, char *data);
  502. void            GetPData(TreeObjHndl hndl, long offset, StringPtr data);
  503. OSErr            PutPData(TreeObjHndl hndl, long offset, StringPtr data);
  504. OSErr            PutShortData(TreeObjHndl hndl, long offset, void *data, unsigned short size);
  505. OSErr            PutLongData(TreeObjHndl hndl, long offset, void *data, long size);
  506. unsigned long    GetDataOffset(TreeObjHndl hndl, unsigned long offset, short dtype, short dnum);
  507.     /* Thees functions are use to get and put data of various sized/kinds out of and into
  508.     ** TreeObj handles.  These are just for convenience, as any data get/put operations
  509.     ** could be done without these functions.  See the document “=Using TreeObj.c” for samples
  510.     ** of using these functions. */
  511.  
  512.  
  513.  
  514. Boolean    EqualTreeObjData(TreeObjHndl h1, TreeObjHndl h2);
  515.     /* Call this function to compare two TreeObj objects.  If there is no procPtr defined for
  516.     ** the object, then this function calls DefaultEqualTreeObjData to do the conparison.
  517.     ** If you have a procPtr defined for the function, then you will probably want to call
  518.     ** DefaultEqualTreeObjData from within your object when you get a COMPAREMESSAGE.
  519.     ** DefaultEqualTreeObjData simply does a byte-per-byte comparison, and if any difference
  520.     ** is found, it returns false.  If all of the bytes are the same, then it returns true.
  521.     ** For deep objects, you will have to write your own comparison.  If you have a handle
  522.     ** stored in the object, then you will need to compare the contents of the handle, instead
  523.     ** of the handle itself.  DefaultEqualTreeObjData doesn't know that the data is actually
  524.     ** a handle.  DefaultEqualTreeObjData does a flat compare. */
  525.  
  526. Boolean    DefaultEqualTreeObjData(TreeObjHndl h1, TreeObjHndl h2);
  527.     /* The default object comparison function.  This simply does a flat-compare of the two
  528.     ** objects. */
  529.  
  530.  
  531. #endif
  532.